def UpdateInstanceByDict(instance, data):
    """
    根据提供的字典数据更新 SQLAlchemy ORM 实例的字段。

    参数:
        instance (db.Model): 需要更新的 SQLAlchemy ORM 实例。
        data (dict): 包含要更新字段及其值的字典。

    返回:
        instance (db.Model): 更新后的 ORM 实例。如果 `data` 为空或 `instance` 为 None，则返回原实例。

    说明:
        - 仅更新 `data` 字典中与实例字段匹配的字段。
        - 如果字段值为 `None`，则不会更新该字段。
    """
    if not instance or not data:
        return instance

    # 获取实例所有字段名称
    columns = {column.name for column in instance.__table__.columns}

    # 计算交集，确保只更新实例已有的字段
    common_fields = columns & data.keys()

    # 遍历交集字段并更新值（跳过 None 值）
    for column_name in common_fields:
        if data[column_name] is not None:
            setattr(instance, column_name, data[column_name])

    return instance


def _isCreateAllow(Class, data):
    """
    检查是否可以创建 SQLAlchemy ORM 实例（是否满足必需字段的要求）。

    参数:
        Class (db.Model): SQLAlchemy ORM 模型类（如 `User`）。
        data (dict): 包含数据的字典。

    返回:
        bool: 如果 `data` 中包含所有必填字段，返回 `True`，否则返回 `False`。

    说明:
        - 必填字段指的是:
            - **不可为空 (`nullable=False`)**
            - **没有默认值 (`default=None`)**
            - **不是主键 (`primary_key=False`)**
            - **不是自增字段 (`autoincrement=False`)**
        - 该函数检查 `data` 是否包含这些字段，并确保值不为 `None`。
    """
    # 获取模型类的所有必填字段
    create_must = [
        column.name
        for column in Class.__table__.columns
        if not column.nullable
        and column.default is None
        and not column.autoincrement
        and not column.primary_key
    ]

    # 确保所有必填字段都存在于 `data` 中且值不为 None
    return all(key in data and data[key] is not None for key in create_must)


def CreateOrUpdateInstanceByDict(Class, instance, data):
    """
    根据字典数据创建或更新 SQLAlchemy ORM 实例。

    参数:
        Class (db.Model): SQLAlchemy ORM 模型类（如 `User`）。
        instance (db.Model | None): 需要更新的 ORM 实例，如果为 `None`，则创建新实例。
        data (dict): 包含字段及其值的字典。

    返回:
        instance (db.Model | None): 更新或新建的 ORM 实例。如果缺少必需字段，则返回 `None`。

    逻辑:
        - 如果 `instance` 为空：
            - 检查 `data` 是否包含所有必需字段。
            - 如果满足条件，创建新的 `instance`，否则返回 `None`。
        - 更新 `instance`，只更新 `data` 中存在且值不为 `None` 的字段。
    """
    if instance is None:
        if not _isCreateAllow(Class, data):
            return None
        instance = Class()

    UpdateInstanceByDict(instance, data)
    return instance


def CreateInstanceByDict(Class, data):
    """
    根据字典数据创建 SQLAlchemy ORM 实例。

    参数:
        Class (db.Model): SQLAlchemy ORM 模型类（如 `User`）。
        data (dict): 包含需要创建的字段及其值的字典。

    返回:
        instance (db.Model | None): 创建的 ORM 实例。如果缺少必需字段，则返回 `None`。

    逻辑:
        - 确保 `data` 包含所有必填字段，否则返回 `None`。
        - 仅设置 `data` 中与模型字段匹配的键，忽略无效字段。
        - 允许 `data` 中缺少非必填字段，此时将使用默认值。
    """
    if not _isCreateAllow(Class, data):
        return None

    instance = Class()
    UpdateInstanceByDict(instance, data)
    return instance
